home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr05 / pdxwn693.zip / MANUAL.TXT < prev    next >
Text File  |  1993-05-15  |  17KB  |  451 lines
  1.                      PROGRAMMING WITH PRTSTR.DLL (5/15/93)
  2.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Introduction:
  5. ~~~~~~~~~~~~~
  6.    Paradox for Windows (PfW) ObjectPAL (OPAL) simply doesn't allow you to
  7.    "take control" of your default Windows printer to output text strings
  8.    directly to it, such as the DOS version of Paradox does.  Therefore, the
  9.    following code is not valid:
  10.  
  11.      prtPrint("Hello Printer!", 1)
  12.  
  13.    ...until now that is!  VS Toolbox Software has now filled this gap in OPAL
  14.    functionality with our new PrintString Windows DLL (PrtStr), designed
  15.    expressly to meet the needs of Paradox for Windows application developers
  16.    just like you.  If you were using PrtStr, the code snippet above would
  17.    print "Hello Printer!" directly to your default Windows printer without your
  18.    having to create a pre-defined PfW "Report"!
  19.  
  20.  
  21. PrtStr Function Overview:
  22. ~~~~~~~~~~~~~~~~~~~~~~~~~
  23.    This Shareware version of PrtStr allows a single instance of your Paradox
  24.    for Windows application to call any of the following 8 functions:
  25.  
  26.       PrtOpen()................... Begins a new printjob
  27.       PrtLines().................. Returns printer's # of lines per page
  28.       PrtChars().................. Returns printer's # of chars per line
  29.       PrtCurrLine()............... Returns the current line # on the page
  30.       PrtPrint(String, SmallInt).. Prints String + SmallInt # of LineFeeds
  31.       PrtLF(SmallInt)............. Prints SmallInt # of blank lines
  32.       PrtFF()..................... Formfeed (starts a new page)
  33.       PrtClose().................. Ends the current printjob
  34.  
  35.  
  36. Paradox for Windows "Uses" Clause:
  37. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38.    The use of any DLL from within PfW, such as PRTSTR.DLL, requires that you
  39.    create a "Uses" clause for the specific DLL and it's functions you want to
  40.    make use of (call).  The PfW Form PRTSTR.FSL, included in this Shareware
  41.    distribution package, provides you with an example of this required code,
  42.    attached to a single button.  Where you locate your PrtStr Uses clause and
  43.    associated calling code (Library, Script or Form) will depend on the
  44.    "scope" you want PrtStr to have in your PfW application.  (Please refer to
  45.    pages 45-53 of the OPAL Reference manual for more information about the
  46.    Uses clause and pages 78-82 of the OPAL Developer's Guide for a discussion
  47.    about Scope.)
  48.  
  49.    The Uses clause necessary for the Shareware version of PrtStr is:
  50.  
  51.       uses PRTSTR
  52.      PrtOpen() CWORD
  53.      PrtLines() CWORD
  54.      PrtChars() CWORD
  55.      PrtCurrLine() CWORD
  56.      PrtPrint(stringVar CPTR, siVar CWORD) CWORD
  57.      PrtLF(siVar CWORD) CWORD
  58.      PrtFF() CWORD
  59.      PrtClose() CWORD
  60.       endUses
  61.  
  62.    NOTE: stringVar is declared as a String and siVar is declared as a SmallInt.
  63.  
  64. PrtOpen():
  65. ~~~~~~~~~~
  66.    The PrtOpen function must be called to BEGIN each new printjob prior to
  67.    calling any other PrtStr function.  PrtOpen does not take any parameters
  68.    and returns a SmallInt value (we call it a Return Code).
  69.  
  70.    PrtOpen performs the following tasks:
  71.  
  72.       * Determines if the printer is already 'open'.
  73.       * Obtains the current default Window's printer driver information.
  74.       * Resets the PrtStr internal 'lines printed' counter to 0.
  75.       * Initiates the Windows Print Manager program (if the printer is
  76.     defined to use the 'Print Spooler').
  77.       * Initiates a Windows Print Manager job.
  78.       * Begins a new Windows 'print' document.
  79.       * If any step fails, returns a negative return code, else it returns 0.
  80.  
  81.  
  82.    Syntax example:  Print the words "Hello Printer!" to the printer...
  83.  
  84.       if PrtOpen() = 0 then
  85.      PrtPrint("Hello Printer!", 1)
  86.      PrtClose()
  87.       else
  88.      msgInfo("PrtStr Error", "Printer Open failed")
  89.       endif
  90.  
  91. PrtLines():
  92. ~~~~~~~~~~~
  93.    The PrtLines function provides your application with the number of lines
  94.    per page allowed by the current printer & page orientation.  This gives you
  95.    an opportunity to code your own page-overflow code, if needed.  PrtLines
  96.    does not take any parameters and returns a SmallInt value.
  97.  
  98.    NOTE: PrtPrint automatically generates a formfeed if it determines that
  99.      the next line to be printed would be off the bottom of the page.
  100.  
  101.  
  102.    Syntax example:  Print a page footer at the bottom of every page...
  103.  
  104.       var
  105.      linesPerPage, currLineNo, loopCounter  SmallInt
  106.      textVar String
  107.       endVar
  108.  
  109.       if PrtOpen() = 0 then                            ;open printer
  110.      linesPerPage = PrtLines()                     ;set lines per page
  111.      for loopCounter from 1 to 100                 ;begin a loop of 100
  112.         if PrtCurrLine() > (linesPerPage - 3) then ;page overflow?
  113.            PrtLF(1)                                ;1 linefeed
  114.            PrtPrint("Page Footer", 1)              ;print page footer
  115.            PrtFF()                                 ;formfeed
  116.         endIf
  117.         textVar = "Line # " + strVal(loopCounter)  ;build a String
  118.         PrtPrint(textVar, 1)                       ;print a line
  119.      endFor                                        ;end of loop
  120.      PrtClose()                                    ;close printer
  121.       else
  122.      msgInfo("PrtStr Error", "Printer Open failed")
  123.       endif
  124.  
  125.  
  126. Character Widths & Line Counts:
  127. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  128.    The following chart is provided for your convenience, as PrtLines and
  129.    PrtChars provide printer and page orientation specific values to your
  130.    program.  The printer font used by the Shareware version of PrtStr is the
  131.    default Windows 'system' font.  This is a fixed-point (non-proportional)
  132.    font, which then makes it easy for you to line up columns in your printout.
  133.  
  134.    If you use a printer other than one of those listed here, run the
  135.    PRTSTR.FSL demo form and it will produce a report that shows you the values
  136.    for your specific printer.
  137.  
  138.           Printer     Orientation   Chars Wide   Lines Long
  139.          ~~~~~~~~~~   ~~~~~~~~~~~   ~~~~~~~~~~   ~~~~~~~~~~
  140.          HP LJII       Portrait         90           63
  141.          HP LJII       Landscape       115           48
  142.  
  143.          Postscript    Portrait        105           76
  144.          Postscript    Landscape       139           57
  145.  
  146.  
  147. PrtChars():
  148. ~~~~~~~~~~~
  149.    The PrtChars function provides your application with the number of
  150.    characters per line allowed by the current printer & page orientation.
  151.    This gives you an opportunity to code a string-length-check so PrtStr
  152.    won't automatically truncate your text string if it's too long.  PrtChars
  153.    does not take any parameters and returns a SmallInt value.
  154.  
  155.    NOTE: PrtPrint automatically truncates your text value to the maximum
  156.      allowable line length specified by the printer and page orientation.
  157.  
  158.  
  159.    Syntax example:  Print the number of characters per line allowed...
  160.  
  161.       var
  162.      textVar  String
  163.       endVar
  164.  
  165.       if PrtOpen() = 0 then
  166.      textVar = "Characters per line = " + strVal(PrtChars())
  167.      PrtPrint(textVal, 1)
  168.      PrtClose()
  169.       else
  170.      msgInfo("PrtStr Error", "Printer Open failed")
  171.       endif
  172.  
  173.  
  174. PrtCurrLine():
  175. ~~~~~~~~~~~~~~
  176.    The PrtCurrLine function provides your application with the current line
  177.    number of the page being printed.  Like PrtLines, this function gives you
  178.    an opportunity to code your own page-overflow code, if needed.  PrtCurrLine
  179.    does not take any parameters and returns a SmallInt value.
  180.  
  181.  
  182.    Syntax example:  Print the current line number on the printout.
  183.             (For a more complex example, refer to PrtLines.)
  184.  
  185.       var
  186.      textVar  String
  187.       endVar
  188.  
  189.       if PrtOpen() = 0 then
  190.      textVar = "Current print line = " + strVal(PrtCurrLine())
  191.      PrtPrint(textVal, 1)
  192.      PrtClose()
  193.       else
  194.      msgInfo("PrtStr Error", "Printer Open failed")
  195.       endif
  196.  
  197.  
  198. PrtPrint(String, SmallInt):
  199. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  200.    The PrtPrint function is the whole reason for the PrintString Windows DLL!
  201.    This function is used to print any PfW/OPAL "string" that you can create.
  202.    If you need to print any type of numerical value, you must first use OPAL's
  203.    strVal() function to convert it to a string.  You may also use OPAL's
  204.    format() function to build a pre-formatted string of text and numbers.
  205.  
  206.    Parameters to pass:
  207.       String is a variable you declare as a String, or a literal text string,
  208.       which contains the actual text you want to have printed.
  209.  
  210.       SmallInit is a variable you declare as a SmallInt, which contains the
  211.       number of linefeeds to be performed after printing the text contained in
  212.       textVar.  A value of 1 tells PrtPrint to add a carriage return/linefeed
  213.       combination to your text.  If you want one or more blank lines printed
  214.       after your text, then set the value of lines at 2 or greater.
  215.  
  216.    PrtPrint performs the following tasks, returning a SmallInt value:
  217.  
  218.       * Checks to make sure the printer is 'open'.
  219.  
  220.       * Checks to make sure the 'textVar' string passed to PrtStr actually
  221.     contains data.  If not, nothing is done.
  222.  
  223.       * Checks to make sure the 'lines' integer passed to PrtStr is greater
  224.     than 0.  If not, it is automatically set to 1.
  225.  
  226.       * Checks the length of the string to be printed.  If it's longer than
  227.     allowed by the current printer and page orientation, it is truncated
  228.     to the maximum line length allowed.
  229.  
  230.       * Checks the current line number.  If it's greater than the allowable
  231.     number of lines per page for the current printer and page orientation,
  232.     an automatic call to PrtFF is performed which generates a Formfeed and
  233.     resets the current line number to 1.
  234.  
  235.       * If all checks are successful:
  236.     * The contents of the textVal string are printed.
  237.     * An automatic call to PrtLF is performed the number of times
  238.       specified via the value in 'SmallInt' (default = 1).
  239.     * A code of 0 is returned to your program.
  240.  
  241.       * If any errors are encountered, a negative return code is returned.
  242.  
  243.  
  244.    Syntax example:  Print text in two different ways...
  245.  
  246.       var
  247.      textVar  String
  248.       endVar
  249.  
  250.       if PrtOpen() = 0 then
  251.          textVar = "Hello printer, this is example text #1"     ;pre-defined
  252.      PrtPrint(textVal, 2)
  253.          PrtPrint("Hello printer, this is example text #2", 1)  ;literal
  254.      PrtClose()
  255.       else
  256.      msgInfo("PrtStr Error", "Printer Open failed")
  257.       endif
  258.  
  259. PrtLF(SmallInt):
  260. ~~~~~~~~~~~~~~~~
  261.    The PrtLF function generates a printer LineFeed which prints a blank line
  262.    the number of times specified via the SmallInt variable.  This function is
  263.    automatically called when PrtPrint() is executed so you don't need to call
  264.    it in your code unless you want extra blank lines printed under specific
  265.    circumstances within your program's control.
  266.  
  267.    PrtLF takes one parameter, SmallInt, which specifies the number of LineFeeds
  268.    to be issued, and returns a SmallInt value.
  269.  
  270.  
  271.    Syntax example:  If some condition is met, print 3 blank lines...
  272.  
  273.       if PrtOpen() = 0 then
  274.      if someConditionIsMet then  ;your own condition goes here
  275.         PrtLF(3)
  276.      endIf
  277.      PrtClose()
  278.       else
  279.      msgInfo("PrtStr Error", "Printer Open failed")
  280.       endif
  281.  
  282.  
  283. PrtFF():
  284. ~~~~~~~~
  285.    The PrtFF function generates a printer FormFeed.  PrtFF is called
  286.    automatically by PrtPrint() if the page's current line number becomes
  287.    greater than the allowable number of lines per page.
  288.  
  289.    PrtFF does not take any parameters, returns a SmallInt value and performs
  290.    the following tasks:
  291.  
  292.       * Issues a FormFeed command to the printer.
  293.  
  294.     If a Formfeed could not be generated due to low memory or low disk
  295.     drive space (unable to continue spooling the printjob):
  296.        * An automatic call to PrtClose is performed, which cancels
  297.          the printjob and resets the printer status to 'Closed'.
  298.        * A Windows message box is displayed to the user (in case they can
  299.          correct the low memory or disk space condition).
  300.        * A negative    return code is sent back to your program.
  301.  
  302.       * Resets the current line number to 1.
  303.  
  304.       * If all went well, a code of 0 is returned to your program.
  305.  
  306.  
  307.    Syntax example:  If some condition is met, start a new page...
  308.  
  309.       if PrtOpen() = 0 then
  310.      if someConditionIsMet then  ;your own condition goes here
  311.         PrtFF()
  312.      endIf
  313.      PrtClose()
  314.       else
  315.      msgInfo("PrtStr Error", "Printer Open failed")
  316.       endif
  317.  
  318. PrtClose():
  319. ~~~~~~~~~~~
  320.    The PrtClose function must be called to END each printjob started with
  321.    PrtOpen.  If it's not called, your report will not be sent from the print
  322.    spooler to the physical printer.  PrtClose does not take any parameters and
  323.    returns a SmallInt value.
  324.  
  325.    PrtClose performs the following tasks:
  326.  
  327.       * Ends the current Windows print document.
  328.       * Ejects the last page of the print document (calls PrtFF).
  329.       * Terminates the Windows Print Manager job which releases it to print.
  330.       * If it was the last print job, Windows closes the Print Manager.
  331.       * Resets the internal Printer 'Open' status to 'Closed'.
  332.       * Resets the current line number to 1.
  333.       * If any step fails, returns a negative return code, else it returns 0.
  334.  
  335.  
  336.    Syntax example:  Close the printer...
  337.  
  338.       If PrtOpen() = 0 then
  339.      PrtPrint("Goodbye printer...", 1)
  340.      PrtClose()
  341.       else
  342.      msgInfo("PrtStr Error", "Printer Open failed")
  343.       endIf
  344.  
  345. PrtStr 'Return Codes':
  346. ~~~~~~~~~~~~~~~~~~~~~~
  347.    Each of the PrtStr functions returns a SmallInt value (CWORD), which is
  348.    referred to as the "return code", to let you know of it's success or
  349.    failure.  The return codes are:
  350.  
  351.        0 = Successful - no further action required.
  352.       -1 = Printer already open - printjob currently in progress.
  353.       -2 = Unable to process a FormFeed request.  Printer is now 'Closed'.
  354.       -3 = Unable to 'Open' a new printjob.  Printer is now 'Closed'.
  355.       -4 = Unable to 'Start' a new printjob.  Printer is now 'Closed'.
  356.       -5 = Printer is not currently 'Open'.
  357.      *-6 = Low disk space encountered by spooler.  Printer is now 'Closed'.
  358.      *-7 = Low memory encountered by spooler.  Printer is now 'Closed'.
  359.  
  360.    * This error will result in a Windows MessageBox being displayed to the
  361.      user, since it may be the result of low memory or low disk space, which
  362.      you might not be able to plan for in your application, but the user might
  363.      be able to fix and re-run the requested job.
  364.  
  365.  
  366. Using PrtStr Return Codes:
  367. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  368.    A typical printout to be generated by PrtStr function calls from within a
  369.    pushButton method might look something like the example on the following
  370.    pages.  (NOTE:  A more complete example is provided 'live' in the
  371.    un-delivered PRTSTR.FSL form included in this Shareware distribution
  372.    package.)
  373.  
  374.    It is suggested that you use this return-code checking method of calling
  375.    PrtStr functions to begin each new report.  Once you are certain that the
  376.    results are what you expect, you can start replacing code.  The one return
  377.    code check which should ALWAYS be performed is PrtOpen.  If PrtStr cannot
  378.    open the printer, all subsequent function calls will fail.
  379.  
  380.  
  381.    Syntax Example:  pushButton method to print "Hello Printer!" and display
  382.             PrtStr errors if any are encountered...
  383.  
  384.  
  385. ;Define variables global to this method...
  386. var
  387.    errMsg                  String
  388.    rtnCode                 SmallInt
  389. endvar
  390.  
  391.  
  392. ;Define the error-handling, on-screen display proc...
  393. proc PrtStrError()
  394.    switch
  395.       case rtnCode = -1 : errMsg = "Printer already 'Open'."
  396.  
  397.       case rtnCode = -2 : errMsg = "Unable to process a FormFeed.\n"
  398.                  + "Printer is Closed."
  399.  
  400.       case rtnCode = -3 : errMsg = "Unable to 'Open' a new printjob.\n"
  401.                  + "Printer is Closed."
  402.  
  403.       case rtnCode = -4 : errMsg = "Unable to 'Start' a new printjob.\n"
  404.                  + "Printer is Closed."
  405.  
  406.       case rtnCode = -5 : errMsg = "Printer is not 'Open'."
  407.  
  408.       case rtnCode = -6 : errMsg = "Print spooler reported low disk space.\n"
  409.                  + "Printjob cancelled. Printer is Closed."
  410.  
  411.       case rtnCode = -7 : errMsg = "Print spooler reported low memory.\n"
  412.                  + "Printjob cancelled. Printer is Closed."
  413.  
  414.       otherwise         : errMsg = "Unknown error returned from PrtStr."
  415.    endswitch
  416.  
  417.    msgInfo("PrtStr DLL Error", errMsg)
  418. endProc
  419.  
  420.  
  421. ;(Start of the actual pushButton method code...)
  422. method pushButton(var eventInfo Event)
  423. ;Open the printer...
  424.    rtnCode = PrtOpen()  ; this gives you a 'return code' you can validate
  425.  
  426. ;Check for errors...
  427.    if rtnCode < 0 then
  428.       PrtStrError()
  429.       return
  430.    endif
  431.  
  432.  
  433. ;Print a line of text...<<to make this fail, comment out the PrtOpen stmt>>
  434.    rtnCode = PrtPrint("Hello Printer!", 1)
  435.    if rtnCode < 0 then
  436.       PrtStrError()
  437.       return
  438.    endif
  439.  
  440.  
  441. ;Close the printer
  442.    rtnCode = PrtClose()
  443.    if rtnCode < 0 then
  444.       PrtStrError()
  445.       return
  446.    else
  447.       msgInfo("Message from PrtStr DLL", "Printjob now completed.")
  448.    endif
  449.  
  450. endmethod
  451.